Summary

Explores @clerk/clerk-js-pinned and @clerk/ui-pinned packages for dependency-managed version pinning without heavy transitive dependencies.

Problem

Today, users can pin:

• @clerk/clerk-js via a string prop like clerkJsVersion="x.y.z"
• @clerk/ui via importing a ui object from @clerk/ui

This is inconsistent and confusing. The naive "make them install @clerk/ui to pin it" approach forces large transitive dependency graphs onto apps that otherwise rely on hot-loaded runtime code.

Proposed Solution

Create lightweight packages that:

• Export only version metadata and types
• Have zero runtime dependencies
• Provide a consistent import surface for pinning both packages
• Bundle all types inline using dts-bundle-generator (no external type dependencies)

New Packages (POC)

@clerk/clerk-js-pinned (~0.34KB gzipped)

• Exports version string constant
• Exports clerkJs branded object for use with new clerkJs prop

@clerk/ui-pinned (~0.41KB gzipped)

• Exports version string constant
• Exports ui branded object with full Appearance type support
• All 1000+ lines of appearance types are bundled inline

Usage

import { clerkJs } from '@clerk/clerk-js-pinned';
import { ui } from '@clerk/ui-pinned';

<ClerkProvider 
  clerkJs={clerkJs}
  ui={ui}
  appearance={{ variables: { colorPrimary: '#000' } }}
  publishableKey="..."
/>

Changes

• Add @clerk/clerk-js-pinned package
• Add @clerk/ui-pinned package
• Add ClerkJs and Ui branded types to @clerk/shared/types
• Add clerkJs prop to IsomorphicClerkOptions
• Update loadClerkJsScript to handle clerkJs object

Open Questions

1. Lock-step Versioning

How do we keep these packages in sync with their parent packages?

Proposed approach: Use changesets fixed groups in .changeset/config.json:

"fixed": [
  ["@clerk/clerk-js", "@clerk/clerk-js-pinned"],
  ["@clerk/ui", "@clerk/ui-pinned"]
]

This ensures when @clerk/clerk-js bumps to 5.115.0, @clerk/clerk-js-pinned automatically gets the same version.

Alternative: CI automation that bumps pinned packages when parent packages bump.

2. Migration Strategy (Backward Compatibility)

The POC maintains the old string-based props for easier migration:

For clerk-js (coexistence):

• clerkJSVersion?: string - existing string-based approach (kept)
• clerkJs?: { version: string } - new branded object approach (added)

The implementation shows precedence: clerkJs?.version ?? clerkJSVersion

For UI:

• ui?: { version: string } - new branded object approach (added)

Questions:

• Should we deprecate clerkJSVersion eventually?
• How do we handle users who have both props set?
• What is the deprecation timeline?

3. Other Open Questions

• Package naming: *-pinned vs something else?
• Release workflow integration
• Documentation approach